.\"Copyright (c) 2011, 2012, 2013 LEVAI Daniel
.\"All rights reserved.
.\"Redistribution and use in source and binary forms, with or without
.\"modification, are permitted provided that the following conditions are met:
.\"	* Redistributions of source code must retain the above copyright
.\"	notice, this list of conditions and the following disclaimer.
.\"	* Redistributions in binary form must reproduce the above copyright
.\"	notice, this list of conditions and the following disclaimer in the
.\"	documentation and/or other materials provided with the distribution.
.\"THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
.\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\"WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\"DISCLAIMED. IN NO EVENT SHALL LEVAI Daniel BE LIABLE FOR ANY
.\"DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\"(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\"LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\"ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\"(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
.\"SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Dd Mar 01, 2013
.Dt KC 1
.Os
.Sh NAME
.Nm kc
.Nd console based username and password management application
.Sh SYNOPSIS
.Nm
.Op Fl k Ar database file
.Op Fl r
.Op Fl p Ar password file
.Op Fl m Ar cipher mode
.Op Fl b
.Op Fl v
.Op Fl h
.Sh DESCRIPTION
The
.Nm
utility is a console based username and password management application using an encrypted XML document as its database.
.Pp
A database file can contain multiple keychains, and keychains in turn can contain multiple keys (usernames if you like) and values (passwords if you like).
.Pp
After starting
.Nm
the
.Cm help
command shows the available commands, and usage information for them. If you're in a hurry, for starters, you create a new entry with the
.Cm new
command, then entering only a number in the command line will display the entry with the given index. You quit from the display with 'q' or EOT (usually CTRL+d).
.Pp
The CLI supports tab-completion for commands and keychains.
.Pp
There is a utility in the source package that converts an exported pwsafe database to a
.Nm
compatible XML database, which can be imported using the
.Cm importxml
command.
.Pp
.Em NOTE :
Currently there is no character set conversion taking place in the program. In this case this means you must be ready to display anything you type in. If somehow you still end up with texts you can not display properly, and for whatever reason you can not edit them in
.Nm ,
you can "repair" such database by dumping its content to a
.Nm
XML file (see the
.Cm dump
command below), converting the plain text XML file to a working character set, then importing back that XML file (see the
.Cm importxml
command below).
.Ss PARAMETERS
.Bl -tag -offset ||| -width |
.It Fl k Ar file
Use
.Ar file
as database. The default is
.Pa ~/.kc/default.kcd .
.It Fl r
Open the database in read-only mode.
.Nm
will not try to lock the database file, and commands which could modify the database will not be available.
.It Fl p Ar file
Read password from
.Ar file .
.It Fl m Ar mode
Cipher mode.
.Ar mode
can be one of 'cbc' (the default), 'cfb128' or 'ofb'. More information is in the
.Em CIPHERS
section.
.It Fl b
Batch mode. Disable some features to enable commands from standard input.
.It Fl v
Display version.
.It Fl h
Display help.
.El
.Ss COMMANDS
These commands are available in the CLI:
.Bl -tag -offset ||| -width |
.It Cm new Op name
Create a new key in the current keychain. Both key and value will be prompted for, except when
.Ar name
is specified; then it will be used as the key's name, up until the first space in
.Ar name .
.Pp
Character sequences can be used in values:
.Pp
"\en" - create a new line, and make the result a multi-line value.
.Pp
"\er", "\eR" - these will be replaced with 2 and 4 (respectively) random printable characters.
.Pp
"\ea", "\eA" - these will be replaced with 2 and 4 (respectively) random alpha-numeric characters.
.Pp
Character sequences are to be used in values, regardless of their order or count, and can be escaped using double backslashes (eg.: "\e\ea").
.It Cm list Op pager Op offset
List
.Ar pager
number of keys per page from the current keychain, skipping
.Ar offset
indices if specified. Every key gets prefixed by its index number. If
.Ar pager
is not specified, the default value of 20 is used. The special value 0 means to not use the pager. If
.Ar offset
is not specified, it is not used.
.It Cm ls Op pager Op offset
Alias of
.Cm list .
.It Cm edit Ar index
Edit a key.
.Ar index
is the key's index number in the current keychain.
.Pp
Character sequence rules in values apply to this command also. See command
.Cm new
for more information about this.
.It Cm swap Ar index Ar index
Swap two keys, exchanging their index numbers. The two
.Ar index
parameters are the keys' index numbers in the current keychain.
.It Cm insert Ar index Ar index
Move the key at the first
.Ar index
parameter to the index at the second
.Ar index
parameter in the current keychain. Surrounding indices will be shifted backwards or forwards.
.It Cm search Ar string
Search for
.Ar string
in key names in the current keychain.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix (eg.: search!): show non-matching keys.
.Pp
.Ql *
suffix (eg.: search*): search in every keychain.
.Pp
.Ql i
suffix (eg.: searchi): case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Cm / Ar pattern
Search for
.Ar pattern
regular expression in key names in the current keychain.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix (eg.: /!): show non-matching keys.
.Pp
.Ql *
suffix (eg.: /*): search in every keychain.
.Pp
.Ql i
suffix (eg.: /i): case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Cm csearch Ar string
Search for
.Ar string
in keychain names.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix (eg.: csearch!): show non-matching keychains.
.Pp
.Ql i
suffix (eg.: csearchi): case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Cm c/ Ar pattern
Search for
.Ar pattern
regular expression in keychain names.
.Pp
Optional modifiers:
.Pp
.Ql \&!
suffix (eg.: c/!): show non-matching keychains.
.Pp
.Ql i
suffix (eg.: c/i): case of characters doesn't matter.
.Pp
You can combine the modifiers.
.It Cm c Ar keychain
Change the current keychain.
.Ar keychain
can be the keychain's index number or name. Index number takes priority when addressing a keychain.
.It Cm cc Ar keychain name
Works like
.Cm c ,
but the keychain's name takes priority over its index number. (see command
.Cm c )
.It Cm cdel Ar keychain
Delete a keychain.
.Ar keychain
can be the keychain's index number or name. Index number takes priority when addressing a keychain.
.It Cm ccdel Ar keychain name
Works like
.Cm cdel ,
but the keychain's name takes priority over its index number. (see command
.Cm cdel )
.It Cm clear Op count
Emulate a screen clearing. Scrolls 50 lines by default, which can be multiplied by
.Ar count
times if specified.
.It Cm clist
List keychains. Every keychain gets prefixed by its index number.
.It Cm cls
Alias of
.Cm clist .
.It Cm cnew Op name
Create a new keychain. If
.Ar name
is not given then prompt for one. Empty string cancels the addition.
.It Cm cedit
Edit the current keychain's name and description.
.It Cm copy Ar index Ar keychain
Copy a key from the current keychain to another keychain.
.Ar index
is the key's index number to copy and
.Ar keychain
is the destination keychain's index number or name. Index number takes priority when addressing a keychain.
.It Cm cp Ar index Ar keychain
Alias of
.Cm copy .
.It Cm move Ar index Ar keychain
Move a key from the current keychain to another keychain.
.Ar index
is the key's index number to move and
.Ar keychain
is the destination keychain's index number or name. Index number takes priority when addressing a keychain.
.It Cm mv Ar index Ar keychain
Alias of
.Cm move .
.It Cm del Ar index
Delete a key.
.Ar index
is the key's index number in the current keychain.
.It Cm rm Ar index
Alias of
.Cm del .
.It Cm passwd
Change the database password. All changes will be written immediately.
.It Cm help Op command
Print application help or describe a
.Ar command .
.It Cm status
Display information about the database.
.It Cm xport Ar filename Op keychain
Export the database to a
.Nm
compatible encrypted database file named
.Ar filename
(if no extension specified, ".kcd" will be appended).
When specifying a keychain, export only that keychain.
.Ar keychain
can be the keychain's index number or name. Index number takes priority when addressing a keychain.
(see command
.Cm dump ,
.Cm import
and
.Cm append )
.It Cm dump Ar filename Op keychain
Dump the database to a
.Nm
compatible XML file named
.Ar filename
(if no extension specified, ".xml" will be appended).
When specifying a keychain, dump only that keychain to the XML file.
.Ar keychain
can be the keychain's index number or name. Index number takes priority when addressing a keychain.
(see command
.Cm xport )
.Em NOTE :
the created XML file will be plain text.
.It Cm import Ar filename
Import and overwrite the current database with the one from a
.Nm
compatible encrypted database file named
.Ar filename .
.Ar filename
must be a proper
.Nm
database. (see command
.Cm importxml ,
.Cm xport
and
.Cm append )
.It Cm importxml Ar filename
Import and overwrite the current database with the one from a
.Nm
compatible XML file named
.Ar filename .
.Ar filename
must contain a properly formatted
.Nm
XML document. (see command
.Cm import ,
.Cm xport
and
.Cm append )
.It Cm append Ar filename
Append new and merge existing keychains to the database from a
.Nm
compatible encrypted database file named
.Ar filename .
.Ar filename
must be a proper
.Nm
database. (see command
.Cm appendxml ,
.Cm xport
and
.Cm import )
.It Cm appendxml Ar filename
Append new and merge existing keychains to the database from a
.Nm
compatible XML file named
.Ar filename .
.Ar filename
must contain a properly formatted
.Nm
XML document. (see command
.Cm append ,
.Cm xport
and
.Cm import )
.It Cm info Op index
Print information about a key in the current keychain or the keychain itself. If
.Ar index
is specified, it is the key's index number in the current keychain. If omitted, information is about the current keychain.
.It Cm quit
Quit the program. If the database has been modified, then ask if it should be saved.
.It Cm exit
Alias of
.Cm quit .
.It Cm random Op length
Print a random string with
.Ar length
length. The default
.Ar length
is 8.
.It Cm version
Display the program version.
.It Cm write
Save the database.
.It Cm save
Alias of
.Cm write .
.It Cm any number
To display a key's value, you enter the key's index (ie.: only a number) into the command line, then it will display the entry with the given index. You quit from the display with 'q' or EOT (usually CTRL+d). By specifying another number after the index (eg.: '12 2' -- here 12 is the index, and 2 is the extra number (spice) after it), that many random characters will be displayed between the value's characters. You can navigate up/down through a multi-line value's lines with keys j/k, n/p, f/b, +/-, [/], {/}, </>, <SPACE>, <ENTER>, <BACKSPACE>. Typing a number between 1-9 will jump directly to that line.
.Pp
Perhaps the extra number (spice) after a key's index and its usefulness can use some further explanation. Let's say you want to display a password to use it on a website's form, but you don't want the people walking by or around you to recognize words, numbers or parts of it. You can use this nifty "trick" to tell
.Nm
to display that many random characters between the value's original characters when showing it to you. Granted, it will look like a mess (although, that is what we wanted), but you can copy-paste it to the password entry in the website form in question. Then you can start to "blindly" delete the given number of characters from it by moving you cursor to the beginning (eg. HOME key), pressing 'spice' numbers of DEL, then jump over one character to the right (with the right arrow key), then delete the random characters again, then repeating this until you reach the end of you original password (those who played Mortal Kombat will feel a bit nostalgic). You can catch on to this, because the random character padding is of fixed length, so the pattern remains the same for the whole password. You don't even have to pay attention to the original length of the password, because after you've completed the pattern (DELs-move-DELs-move...) and removed the spice (ie.: every padding random character), you end up with you original password, and you'll just be deleting nothing after the end of the string. This of course only makes sense if the form is a password input field, so you (and everybody else) just see stars or dots in place of the password.
.El
.Ss CIPHERS
All ciphers use 128 bit keys, generated with a KDF (key-derivation function) from the supplied password, an IV (initialization vector) and a salt. Both the IV and the salt are 128 bits long and read from the host's specific random device (
.Pa /dev/urandom
on Linux and
.Pa /dev/random
on everything else ).
.Sh EXAMPLES
.Bl -tag -offset ||| -width |
.It Em pwsafe_to_kc.pl :
.Bd -literal -offset |||
# Export the pwsafe database to a cleartext file:
$ pwsafe --exportdb > pwsafe_export
Enter passphrase for .pwsafe.dat:

# Convert the cleartext pwsafe database to a kc XML database file:
$ pwsafe_to_kc.pl pwsafe_export kc_db.xml
opening pwsafe_export for reading.
opening kc_db.xml for writing.
Converting...
Done.
.Ed
.Pp
After the above commands, you should end up with a
.Nm
compatible XML database. You can import it to
.Nm
using the
.Cm importxml
command.
.It Em Adding new entries :
.Bd -literal -offset |||
.Em Simple :
default% > new testuser
default% NEW value> testpass

.Em Prompt for both key and value :
default% > new
default% NEW key> testuser2
default% NEW value> test_\er_pass_with_random_characters:\eA

.Em Using the 'key' only as an indication :
default% > new www.mysecuresite.com
default% NEW value> user_name\enpass-word

.Em Using the random and newline character sequences :
default% > new testuser3
default% NEW value> \er\eR\en\ea\eA\enthis is a multi-line value!

.Em Creating new keychains :
default% > cnew email_accounts
default% > cnew
default% NEW keychain name> WebSite Accounts
default% NEW keychain description> description

.Em Results :

.Em Listing the keys in the current keychain :
default% > list
0. testuser
1. testuser2
2. www.mysecuresite.com
3. testuser3

.Em Displaying values in the current keychain :
default% > 0
[testuser] testpass
default% > 1
[testuser2] test_,x_pass_with_random_characters:6nzm
default% > 2
[www.mysecuresite.com] [1/2] user_name
[www.mysecuresite.com] [2/2] pass-word
default% > 3
[testuser3] [1/3] v#)z!9
[testuser3] [2/3] HwRz7i
[testuser3] [3/3] this is a multi-line value!

.Em Listing keychains :
default% > clist
0. default
1. email_accounts
2. WebSite Accounts

.Em Switch to another keychains :
default% > c email_accounts
email_accounts% > c 2
WebSite Accounts% >
.Ed
.It Em Editing existing entries :
.Bd -literal -offset |||
default% > list
0. testuser
1. testuser2
2. www.mysecuresite.com
3. testuser3

.Em Edit an entry in the current keychain :
default% > edit 1
default% EDIT key> testuser2
default% EDIT value> test_pass_with_random_characters:6nzm
default% > 1
[testuser2] test_pass_with_random_characters:6nzm

.Em Rename a keychain :
default% > cedit default
default% EDIT keychain name> my_own keychain
default% EDIT keychain description> description
my_own keychain% >
.Ed
.El
.Sh CAVEATS
If you use 'cfb128' or 'ofb' for cipher, there is no specific sign if you enter a wrong password during the opening of a database; in this case the database would seem to be corrupt after decrypting, and
.Nm
will not be able to open it.
.Pp
If you use
.Cm xport
to export to an encrypted
.Nm
database, it is not possible to choose a different cipher mode than the one being used with the current database. It is also not possible to choose a cipher mode during an
.Cm import
of an encrypted
.Nm
database, and the one being utilized by the current database will be used.
.Pp
There is no character conversion taking place for the input fields.
.Sh AUTHOR
.Nm
was written by
.An LEVAI Daniel
<leva@ecentrum.hu>
.Pp
Source, information, bugs:
http://keychain.googlecode.com
